Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 3 - Text Encoding Converter Reference / Text Encoding Converter Functions

Identifying Possible Destination Encodings /

TECCountDestinationTextEncodings

Counts and returns the number of destination encodings possible for the specified source encoding using a single-step, direct conversion.

pascal OSStatus TECCountDestinationTextEncodings (
                     TextEncoding inputEncoding,
                     ItemCount *numberOfEncodings);

inputEncoding

The text encoding specification describing the source text.

numberOfEncodings

A pointer to a value of type ItemCount. On output, this value indicates the number of text encodings to which the source encoding given in the inputEncoding parameter can be directly converted.

function result

A result code. See "Text Encoding Conversion Manager Result Codes" (page 42) for a list of possible values. If other than noErr, then one of the text conversion plug-ins encountered an error when polled by the Text Encoding Converter

DISCUSSION

The TECCountDestinationTextEncodings function returns the number of direct conversions possible from the specified source encoding to any supported destination encodings. A direct encoding conversion consists of a conversion from the source encoding to a destination encoding without any intermediate conversions (that is, only one plug-in conversion function needs to be called). For example, suppose Mac OS Japanese is the source encoding. If a plug-in contains a Mac OS Japanese to ISO 2022-JP function, then conversion from Mac OS Japanese to ISO 2022-JP can be a direct (that is, a one-step) conversion. However, if no such function exists, the conversion must take place indirectly (for example, from Mac OS Japanese to EUC-JP and then from EUC-JP to ISO 2022-JP).

You can use the number that this function returns to determine how many text encoding specification elements to allocate for the array you pass to the function TECGetDestinationTextEncodings (page 74).

TECCountDestinationTextEncodings counts each instance of the same encoding. That is, if different conversion plug-ins support the same text encoding for any of the conversion processes they provide, this function includes each instance of the text encoding in its sum. Consequently, the same text encoding may be counted more than once. Since the TECGetDestinationTextEncodings function does not return duplicate text encoding specifications, TECCountDestinationTextEncodings may return a number greater than the number of array elements required.